home *** CD-ROM | disk | FTP | other *** search
/ Aminet 6 / Aminet 6 - June 1995.iso / Aminet / dev / debug / PoolWatch1_01.lha / PoolWatch1_01 / PoolWatch.doc next >
Encoding:
Text File  |  1995-04-06  |  8.2 KB  |  218 lines
  1. Short: Debug tool for pool-allocations, a la Mungwall (OS3.x)
  2. Type: dev/debug
  3. Author: Magne Oestlyngen (magneo@stud.cs.uit.no)
  4. Uploader: Magne Oestlyngen (magneoe@stud.cs.uit.no)
  5.  
  6. ------------------==================================------------------
  7. 950406
  8.                         PoolWatch release 1.01
  9.  
  10.             Requires AmigaDOS 3.0 (V39) or higher to run.
  11.  
  12.              Copyright © 1994-1995 Ultima Thule Software
  13.                          All Rights Reserved.
  14.  
  15.                        Author: Magne Østlyngen
  16.  
  17. ------------------==================================------------------
  18.  
  19. Disclaimer
  20. ~~~~~~~~~~
  21. This  software  entitled  "PoolWatch"  is not public domain but freely
  22. distributable (FreeWare).  This means that you can copy it and give it
  23. to all your friends, upload it to a BBS or include it in a PD-library.
  24. The  only  restrictions  are:   All the files included in this archive
  25. must  be  in  their  original  form  without  additions,  deletions or
  26. modifications  of  any  kind.   PoolWatch  may  not be distributed for
  27. profit,  and  only  a  nominal  charge  may  be  associated  with  its
  28. distribution.   Permission  is hereby given to distribute PoolWatch on
  29. the  Fish  disks  (CD  or  floppy)  and the AmiNet CD.  If you want to
  30. distribute  "PoolWatch"  with  any  commercial  product, you will need
  31. written  permission  from the author.  "PoolWatch" is provided "AS IS"
  32. without  warranty  of  any kind, and the author is not responsible for
  33. any damage this software may do.  (Just in case :-)
  34.  
  35.  
  36. What is PoolWatch ?
  37. ~~~~~~~~~~~~~~~~~~~
  38. PoolWatch  is a debug tool for OS 3.0 and higher designed to watch and
  39. correct  illegal  allocation  and  freeing  of  memory  that  use  the
  40. pool-functions provided in OS 3.0 and upwards.  PoolWatch is necessary
  41. since  Mungwall  do  not  catch any illegal memory handling concerning
  42. pool-allocations.
  43.  
  44. PoolWatch  is especially useful in combination with Enforcer, Mungwall
  45. (which  will  watch  normal  allocations  that  use AllocMem/FreeMem),
  46. SegTracker and FindHit (included in the Enforcer archive).
  47.  
  48. If  SegTracker  is  running  in  the system when PoolWatch is started,
  49. PoolWatch   will  use  the  public  SegTracker  seglist  tracking  for
  50. identifying  the  hunk  and  offset  into the executable doing illegal
  51. allocations.
  52.  
  53. You  *need*  sushi  to run PoolWatch.  PoolWatch will use kprintf() to
  54. output  text, and without sushi (or a terminal-program :) you will not
  55. be able to see the text.  Future versions will probably support output
  56. to stdio too.
  57.  
  58.  
  59. What does PoolWatch do ?
  60. ~~~~~~~~~~~~~~~~~~~~~~~~
  61. PoolWatch  will  patch  CreatePool(), DeletePool(), AllocPooled(), and
  62. FreePooled()  in exec.library.  PoolWatch will use these functions but
  63. will add extra security on top of all pool-allocations.  In most cases
  64. of  illegal allocation/freeing, PoolWatch will report the error to the
  65. user  and  correct  the  problem  (if  possible).   Please  note  that
  66. PoolWatch  does  not offer any memory protection if a task writes to a
  67. random  addresse  in  memory,  but  will  take  care  of most problems
  68. associated with pool allocations.
  69.  
  70.  
  71. In detail, PoolWatch will do the following things:
  72. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  73.  
  74. CreatePool()
  75. ¯¯¯¯¯¯¯¯¯¯¯¯
  76. -  PoolWatch will check and warn you if the tresh-size if greater than
  77. the puddle-size.
  78.  
  79. -  PoolWatch will add the pool to its private list of pools created by
  80. PoolWatch.
  81.  
  82. AllocPooled()
  83. ¯¯¯¯¯¯¯¯¯¯¯¯¯
  84. -  PoolWatch  will  verify  that  the pool pointer is within the valid
  85. ram-area,  and  warn you if it's not (this will also take care of NULL
  86. pool pointers).
  87.  
  88. -  PoolWatch will check if the pool was created by PoolWatch.  If not,
  89. the  pool  pointer  will  be  passed directly to AllocPooled() in exec
  90. without modifications.
  91.  
  92. -  PoolWatch  will  add  a  wall  of  32  bytes  on  each  side of the
  93. allocation,   and   later   check  these  walls  in  DeletePool()  and
  94. FreePooled().
  95.  
  96. -  Except when MEMF_CLEAR is set, memory is filled with $DEADFOOD.  If
  97. this number shows up in an Enforcer or PoolWatch report, the caller is
  98. allocating memory and doesn't initialize it before using it.
  99.  
  100. - PoolWatch will check and warn you if 0 bytes of memory is requested.
  101.  
  102. FreePooled()
  103. ¯¯¯¯¯¯¯¯¯¯¯¯
  104. -  PoolWatch  will verify that the pool and memory pointers are within
  105. the  valid  ram-area, and warn you if they're not (this will also take
  106. care of NULL pool and memory pointers).
  107.  
  108. -  PoolWatch will check if the pool was created by PoolWatch.  If not,
  109. the  pool  pointer  will  be  passed  directly to FreePooled() in exec
  110. without modifications.
  111.  
  112. - PoolWatch will check if the memory if freed with the correct length,
  113. and  warn  you  if not.  PoolWatch will ofcourse free the memory using
  114. the correct length.
  115.  
  116. -  The allocation will be checked to make sure the walls have not been
  117. overwritten.
  118.  
  119. -  Memory  is  filled  with  $DEADBEEF before it is freed, encouraging
  120. programs reusing freed memory to crash.
  121.  
  122. DeletePool()
  123. ¯¯¯¯¯¯¯¯¯¯¯¯
  124. -  PoolWatch  will  verify  that  the pool pointer is within the valid
  125. ram-area,  and  warn you if it's not (this will also take care of NULL
  126. pool pointers).
  127.  
  128. -  PoolWatch will check if the pool was created by PoolWatch.  If not,
  129. the  pool  pointer  will  be  passed  directly to DeletePool() in exec
  130. without modifications.
  131.  
  132. -   If  the  pool  was  allocated  by  PoolWatch,  all  the  remaining
  133. allocations   will  be  checked  to  make  sure  no  walls  have  been
  134. overwritten.
  135.  
  136. -  Memory  is  filled  with  $DEADBEEF before it is freed, encouraging
  137. programs reusing freed memory to crash.
  138.  
  139.  
  140. If  Mungwall  is running, PoolWatch won't mung the memory itself (fill
  141. it   with   $DEADF00D/$DEADBEEF),  but  will  let  Mungwall  do  that.
  142. PoolWatch  decides  on  startup if memory should be munged, by looking
  143. for  Mungwalls messageport.  If you start/stop mungwall after starting
  144. PoolWatch,  you  can  ask PoolWatch to update its internal settings by
  145. issuing it a CTRL-F.
  146.  
  147.  
  148. Usage
  149. ~~~~~
  150. If  you  type  only  "PoolWatch"  on  the command line, PoolWatch will
  151. default  to serial output for showing messages.  PoolWatch will output
  152. the  debug  info  to the serial port with the function kprintf().  You
  153. can  use  a  local  serial debug capture tool such as Sushi to capture
  154. this output and display it in a standard console window.
  155.  
  156. PoolWatch can *not* be run from Workbench.
  157.  
  158. -Q=QUIT
  159. The  QUIT option (-Q for short) will signal PoolWatch to quit.  If all
  160. memory  allocated  by  PoolWatch has been freed, PoolWatch will remove
  161. its patches and quit.
  162.  
  163.  
  164. History
  165. ~~~~~~~
  166.  
  167. v1.0 (5-Apr-95):
  168. - Initial release 1.0 of PoolWatch.
  169.  
  170. v1.01 (6-Apr-95):
  171. - Oh,  great.   Just  after  release,  I found out that compiling with
  172.   optimize  wasn't  too  smart, since it removed some important bytes.
  173.   Worked around the problem.
  174.  
  175.  
  176. **********************************************************************
  177. ***************************** REMEMBER *******************************
  178. **********************************************************************
  179.  
  180. *NOTHING* should cause PoolWatch to react.  If all pool allocations in
  181. an  application are handled correctly, there's no reason for PoolWatch
  182. to  give warnings.  Software that use illegal allocations or overwrite
  183. existing  memory  will not function properly in AmigaOS and will crash
  184. the  system  or  other  programs.  If you use PoolWatch and discover a
  185. problem  with  a  program, please notify the author of that program so
  186. the  problem  can  be  fixed.  *All* application writers that use pool
  187. allocations  should test their applications extensivly with PoolWatch,
  188. Mungwall, Enforcer and SegTracker.
  189.  
  190. **********************************************************************
  191.  
  192.  
  193. FeedBack
  194. ~~~~~~~~
  195. Please  send  donations  (Yeah,  it's  FreeWare, but you _can_ send me
  196. money,  gifts,  chocolate, email, snailmail, etc...), bug reports or a
  197. list  of  features  you would like to have included in future releases
  198. (if the feedback is big enough, there might even _be_ future releases)
  199. to:
  200.  
  201. Magne Østlyngen
  202. Strandveien 59B
  203. N-9007 Tromsø
  204. Norway
  205.  
  206. Email: magneoe@stud.cs.uit.no (Magne Oestlyngen)
  207. Fido: 2:212/8.15 (Magne Oestlyngen)
  208.  
  209. You can also get in touch with me at the following BBSes in Norway:
  210. Ultima Thule and Abbs Support.
  211.  
  212.  
  213. Thanks to
  214. ~~~~~~~~~
  215.  Petter Nilsen      for writing the initial documentation, useful suggestions and beta-testing.
  216.  Jan Van den Baard  for betatesting
  217.  Michael Sinz       for Enforcer
  218.